home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / c / matrx042.zip / MATRIX.DOC < prev    next >
Text File  |  1994-04-16  |  18KB  |  483 lines
  1. /*
  2. *-----------------------------------------------------------------------------
  3. *       file:   matrix.doc
  4. *       desc:   document for matrix toolbox function calls
  5. *       by:     KO shu pui, patrick
  6. *       date:   24 may 92       v0.4
  7. *               23 sep 93       v0.41
  8. *               16 apr 94       v0.42
  9. *-----------------------------------------------------------------------------
  10. */
  11.  
  12. ===============================================================================
  13. 0. INTRODUCTION
  14. ===============================================================================
  15. This document only provides you the following information:
  16.  
  17.         0.1     How to create and free a matrix
  18.         0.2     Description of each matrix function call
  19.         0.3     Some hints to use this toolbox
  20.  
  21. Remember that this document will NOT describe the data structure and
  22. any technical details of the toolbox - just because this document is
  23. aimed at to be a sort-of "User's Guide" for programmers.
  24.  
  25.  
  26.  
  27.  
  28. ===============================================================================
  29. 1. OUR MATRIX OF REFERENCE
  30. ===============================================================================
  31. In order to avoid terms confusion, here is our matrix of reference
  32. (matrix A) which is of size m x n.
  33.  
  34.                           Column
  35.                 Row        0       1       2          n-1
  36.                  0    [   a0,0    a0,1    a0,2   ...  a0,n-1   ]
  37.      A =         1    [   a1,0    a1,1    a1,2   ...  a1,n-1   ]
  38.                  2    [   a2,0    a2,1    a2,2   ...  a2,n-1   ]
  39.                       [   ...     ...     ...    ...  ...      ]
  40.                  m-1  [   am-1,0  am-1,1  am-1,2 ...  am-1,n-1 ]
  41.  
  42.  
  43.  
  44. ===============================================================================
  45. 2. BASIC MATRIX OBJECT OPERATION
  46. ===============================================================================
  47. -------------------------------------------------------------------------------
  48. Function :      MATRIX mat_creat (int m, int n, int type)
  49. Synopsis :      creation of a matrix which can be used by the matrix toolbox
  50.                 functions; memory is allocated for this object; and some
  51.                 initialization is performed.
  52. Parameter:      m: number of rows
  53.                 n: number of columns
  54.                 type: matrix initialization type where
  55.  
  56.                 type=
  57.  
  58.                 UNDEFINED       do not initialize the matrix
  59.                 ZERO_MATRIX     fill zero to all matrix elements
  60.                 UNIT_MATRIX     fill a one to all matrix element ai,j
  61.                                 where i=j
  62.  
  63. Return Value:   the matrix object
  64. Example:
  65.  
  66.                 MATRIX  A;
  67.  
  68.                 /*
  69.                 * create a 15 x 15 matrix;
  70.                 * do not initialize the elements
  71.                 */
  72.                 A = mat_creat( 15, 15, UNDEFINED);
  73.  
  74.                 /*
  75.                 * put a 4 in element A(0,14) of matrix A,
  76.                 * put a 2 in element A(3,5) of matrix A
  77.                 */
  78.                 A[0][14] = 4.0;
  79.                 A[3][5] = 2.0;
  80.  
  81. See Also:       mat_free(), for Accessing a matrix, see this example.
  82. -------------------------------------------------------------------------------
  83. Function:       MATRIX mat_fill ( MATRIX A, int type )
  84. Synopsis:       initialize a matrix will a simple type
  85. Parameter:      A: the matrix object for which mat_creat() has been called
  86.                 type: matrix initialization type where
  87.  
  88.                 type=
  89.  
  90.                 UNDEFINED       do not initialize the matrix
  91.                 ZERO_MATRIX     fill zero to all matrix elements
  92.                 UNIT_MATRIX     fill a one to all matrix element ai,j
  93.                                 where i=j
  94. Return Value:   MATRIX A
  95. Example:
  96.  
  97.                 MATRIX  A;
  98.  
  99.                 ...
  100.                 /*
  101.                 * fill the matrix A will zeroes
  102.                 */
  103.                 mat_fill( A, ZERO_MATRIX );
  104.  
  105. See Also:       mat_creat()
  106. -------------------------------------------------------------------------------
  107. Function :      int mat_free ( MATRIX A )
  108. Synopsis :      free all memory occupied by the matrix object A
  109. Parameter:      A: the matrix object for which mat_creat() was called
  110. Return Value:   None
  111. Example:
  112.  
  113.                 MATRIX  A;
  114.  
  115.                 A = mat_creat(...);
  116.                 ...
  117.                 mat_free(A);
  118.  
  119. Note:           since memory may be a very scarce resource in a computer,
  120.                 as a C programmer you are advised to free up the matrix as
  121.                 soon as that matrix will not be used any more in future.
  122.  
  123. See Also:       mat_creat()
  124. -------------------------------------------------------------------------------
  125. Function:       MatCol ( A )
  126. Synopsis:       find out the number of columns of a matrix object A
  127. Parameter:      A: the matrix object for which mat_creat() was called
  128. Return Value:   number of columns
  129. Example:
  130.                 int     i;
  131.  
  132.                 ...
  133.                 i = MatCol(A);
  134.  
  135. Note:           this is a macro
  136. See Also:       MatRow()
  137. -------------------------------------------------------------------------------
  138. Function:       MatRow ( A )
  139. Synopsis:       find out the number of rows of a matrix object A
  140. Parameter:      A: the matrix object for which mat_creat() was called
  141. Return Value:   number of rows
  142. Example:
  143.                 int     i;
  144.  
  145.                 ...
  146.                 i = MatRow(A);
  147.  
  148. Note:           this is a macro
  149. See Also:       MatCol()
  150.  
  151. -------------------------------------------------------------------------------
  152. Function:       MATRIX mat_colcopy1 ( MATRIX A, MATRIX B, int j1, int j2 )
  153. Synopsis:       copy a column from a matrix A to a column at matrix B
  154. Parameter:      A, B: the matrix objects for which mat_creat() was called
  155.                 column j1 of A is copied to column j2 of B;
  156. Return Value:   MATRIX A
  157. Example:
  158.                 MATRIX  A, B;
  159.  
  160.                 A = mat_creat( 5, 4, ZERO_MATRIX );
  161.                 B = mat_creat( 5, 4, UNDEFINED );
  162.  
  163.                 /*
  164.                 * copy column 2 of A to column 0 of B
  165.                 */
  166.                 mat_colcopy1( A, 2, B, 0 );
  167.  
  168. Note:           the sizes of rows of A, B must be the same
  169. See Also:       mat_copy()
  170. -------------------------------------------------------------------------------
  171. Function:       MATRIX mat_copy ( MATRIX A )
  172. Synopsis:       duplicate a matrix
  173. Parameter:      A: the matrix object for which mat_creat() was called
  174. Return Value:   Another allocated matrix object whose contents are same
  175.                 as A
  176. Example:
  177.                 MATRIX  A, B;
  178.  
  179.                 A = mat_creat( 5, 4, ZERO_MATRIX );
  180.  
  181.                 /*
  182.                 * B is also a 5 x 4 zero matrix now
  183.                 */
  184.                 B = mat_copy( A );
  185.                 ...
  186.                 mat_free( B );
  187.  
  188. See Also:       mat_colcopy1()
  189. -------------------------------------------------------------------------------
  190.  
  191.  
  192.  
  193.  
  194. ===============================================================================
  195. 3. BASIC MATRIX OBJECT INPUT/OUTPUT OPERATION
  196. ===============================================================================
  197. -------------------------------------------------------------------------------
  198. Function:       int fgetmat (MATRIX A, FILE * fp)
  199. Synopsis:       read a matrix from stream
  200. Parameter:      A: allocated matrix
  201.                 fp: a stream pointer obtained from fopen() or predefined
  202.                 pointer in standard library such as stdin
  203. Return Value:   number of matrix elements read
  204. Example:
  205.                 MATRIX  A;
  206.                 FILE    *fp;
  207.  
  208.                 A = mat_creat(3, 3, UNDEFINED);
  209.                 fp = fopen("mymatrix.dat", "r");
  210.                 fgetmat( A, fp );
  211.  
  212. See Also:       mat_dumpf(), mat_dump(), mat_fdump(), mat_fdumpf()
  213. -------------------------------------------------------------------------------
  214. Function:       MATRIX mat_dump   (MATRIX A)
  215.                 MATRIX mat_dumpf  (MATRIX A, char * format)
  216.